Introduction
Fleek Network's Lightning source code is updated frequently and thus keeping up with changes can be a bit of a chore and especially difficult for users who are trying to have it compiled for the first time, or updating the Lightning CLI binary for their operating systems. While we should have stable releases in the future, at the current phase of development, there's a requirement to follow the contributions directly in the repository: checking in and out, the commits you're interested in running.
In the following guide, we’ll have a simple look into how to pull changes and update Lightning CLI on Linux, which we stick with Ubuntu for simplicity but should be easily transferrable to your supported OS.
Pre-requisites
To follow the guide, you will need the following:
- Familiarity with the command-line interface
- Some experience with Git
- Have installed and set up the Lightning CLI and service
Stop the Lightning Service
Before proceeding, it's best to stop the Lightning Service to perform the update.
To prevent any negative impact on the node's reputation, it's advisable to wait until the end of the Epoch (~24h) before shutting down the node when opting out. The same applies to nodes that have opted-in but are currently offline.
To learn more, read the Lightning-CLI section for command opt.
Stop the Lightning Service by executing the command:
sudo systemctl stop lightning
Shutting down a Node after an Epoch can be tedious, given the remaining time an Epoch can take to end. Doing it prematurely, will cause reputation penalties, e.g. shutting down before the participation state change to offline. Therefore, a shutdown utility is available in the Tools menu option of get.fleek.network.
To access it, execute the command:
curl https://get.fleek.network | bash
Pulling the latest changes
Check the latest contributions pushed to the Lightning CLI main branch, it'll give you clarity on what's been committed into the source code. Therefore, find out about new features, fixes, improvements, etc by looking directly into the repository history.
Switch to installer username
First, switch to the username you've used to install and setup Fleek Network Lightning.
To switch to the username you've used throughout the installation process do:
su <USERNAME>
For example, if you used the username lgtn it'll look like the following command:
su lgtn
Change directory to the source code
Next, change directory to the Lightning directory in your file system.
The tild ~ means user $HOME, thus you have to be logged in with the correct user as requested in the installer username step.
cd <PATH-TO-LIGHTNING-SOURCE-CODE>
If you have installed it via the recommended instructions, then the default location where the source code is stored should be ~/fleek-network/lightning. Otherwise, if you opted-in for a custom location then look into your notes before proceeding.
For example, it'd look like the following command:
cd ~/fleek-network/lightning
Checkout to branch
Make sure that you are checked in to the correct branch. For example, if that'd be the first testnet phase it'd be called testnet-alpha-1.
git checkout <BRANCH-NAME>
Here's an example of how the command would look like for the main default branch with corresponding name main.
git checkout main
During testnet phase, you have to checkout to the testnet branch. For example, the first testnet branch name was testnet-alpha-1 that you would have to be checked in order to run a node successfully. A list of the active branches can be found at anytime in the GitHub repository active branches. While we try our best to update documentation, guides, instructions or any other written content during development, there might be breaking changes that might take some time to reflect in our documents. To avoid disappointment, check into the correct branch or contribute by getting in touch with us, or sending a PR in the relevant context, thank you!
Here's an example of how the command would look like for the branch name testnet-alpha-1.
git checkout testnet-alpha-1
Pull the latest changes
The syntax to pull the latest commits is the following:
git pull <REPOSITORY-NAME> <BRANCH-NAME>
The git pull command is used to fetch and merge changes from the remote repository to the local repository. Here we're pulling from remote named origin and branch main.
git pull origin main
If you've made any changes in the local repository directory, clear them to prevent being blocked. As git is a version control program that looks for changes and will ask you to do something about it to prevent losing data. Most readers can disregard changes if not contributing to the development by simply stashing or resetting the changes.
A quick way to clean is to stash the changes, for example:
git stash
You can check yourself, as follows:
git remote -v
Our output clearly describes what origin is tracking.
origin git@github.com:fleek-network/lightning.git (fetch)
origin git@github.com:fleek-network/lightning.git (push)
Alternatively, you can stash and pull, to reset the repository to the origin.
git fetch origin <BRANCH-NAME>
git reset --hard origin/<BRANCH-NAME>
git clean -f
With git you can point to any point in the repository history, there might be lots of reasons you'd want to check into a certain commit or branch, e.g. if you encounter bugs and need to revert to a previous commit or version. That being said, we welcome all kinds of contributions, such as simply reporting bugs. To report issues in our repository visit the issues page to help us improve.
Here's the output we got after the git pull:
remote: Enumerating objects: 437, done.
remote: Counting objects: 100% (437/437), done.
remote: Compressing objects: 100% (205/205), done.
remote: Total 397 (delta 242), reused 334 (delta 181), pack-reused 0
Receiving objects: 100% (397/397), 214.68 KiB | 4.77 MiB/s, done.
Resolving deltas: 100% (242/242), completed with 29 local objects.
From https://github.com/fleek-network/lightning
* branch main -> FETCH_HEAD
12b2647..998108d main -> origin/main
Updating 12b2647..998108d
Fast-forward
.dockerignore | 6 -
.gitignore | 2 +
Cargo.lock | 782 +++++++----------------
Cargo.toml | 2 +-
core/application/src/state.rs | 12 +-
core/cli/Cargo.toml | 47 ++
core/cli/readme.md | 59 ++
core/cli/src/args.rs | 63 ++
core/cli/src/cli.rs | 136 ++++
core/cli/src/commands/dev.rs | 112 ++++
core/cli/src/commands/key.rs | 92 +++
...
When your local version of the repository, is up-to-date with the remote repository, you'd get:
From https://github.com/fleek-network/lightning
* branch main -> FETCH_HEAD
Already up to date.
A "already up to date" message means that you have the latest version of the source code and can proceed with compiling the binary process from the source code to override the Lightning CLI version you're on. You can also make any other setup changes that might find necessary. Some changes might be related to the recommended setup of Systemd Service that helps control the Fleek Network Lightning Node binary process, etc.
Build the binary from the source code
We're assuming that your system setup hasn't changed, such as Rust toolchain still being installed and setup correctly in the system and any other required dependencies. If you have made changes to your system and need to revisit the setup instructions, check our install document here.
First, switch the user and change directory to the Lightning directory in your file system as described in switch to installer username change directory to the source code sections.
Recall the command from our install document or getting started guide? As you probably guessed, you need to execute the rust cargo build command. But firstly, we are going to clean and update the Rust package manager, as follows:
cargo clean
cargo update
Next, execute the build command to compile the Fleek Network Lightning CLI binary.
cargo +stable install --locked --path core/cli --features services
The build command uses the Rust compiler, which might take a while depending on how speedy the host machine is capable.
Once the Rust compiler completes, the generated binary will be available in the source code project directory.
If you have stick with the default recommendation, that'll be at ~/.cargo/bin/lightning-node.
Checkup the symlink setup
During the original install and setup process, a symbolic link (symlink) was created linking the generated binary file located in ~/.cargo/bin/lightning-node to /usr/local/bin/lgtn. By placing the symlink in the default installation location of the user, the executable application is available globally as lgtn.
You can see the full absolute path of the symlink and verify if setup correctly by running:
readlink -f <SYMLINK-NAME>
If you have followed the recommended name, the symbolic link should be called lgtn, short version for lightning.
readlink -f lgtn
Here's an example where we find the symlink lgtn pointing to the absolute path where our source code and originated built binary is located, as described in the build the binary from the source code section.
/home/<USERNAME>/.cargo/bin/lightning-node
Alternatively, you can use the ls command to identify the symlink.
ls -la $(which lgtn)
If you find an error, it's very likely that a symlink is not setup. You can revisit the installation to learn, or execute the command to link the build binary to the user default install location:
sudo ln -s "~/.cargo/bin/lightning-node" /usr/local/bin/lgtn
Make sure that the paths provided to the command ln are correct. If you are using customized pathnames or switched to a different username other than the one used for installation it has to change accordingly.
Systemd service
It's highly recommended to use systemd to manage the Fleek Network service for node operators. Systemd is a system and service manager for Linux operating systems that provides a consistent way to manage system services across various distributions.
Verify the setup
The recommended setup is to wrap the Lightning binary process as a Systemd service, as instructed in the install section.
If you have followed the recommendations, you should have the service file called ligthning.service in the path /etc/systemd/system/lightning.service.
The content of lightning.service should have some or more of the following properties and values:
[Unit]
Description=Fleek Network Node lightning service
[Service]
Type=simple
MemoryHigh=32G
RestartSec=15s
Restart=always
ExecStart=lgtn -c /home/lgtn/.lightning/config.toml -vv run
StandardOutput=append:/var/log/lightning/output.log
StandardError=append:/var/log/lightning/diagnostic.log
Environment=TMPDIR=/var/tmp
[Install]
WantedBy=multi-user.target
Every time the file is modified, the Systemd process should be reloaded. You can do this by executing:
sudo systemctl daemon-reload
To learn more about how to create a Systemd service read the manual installation document that illustrates the steps required in greater detail.
Network participation status
The Node Network participation should be truthy (online). Verify the status by executing the command:
lgtn opt status
Before proceeding, make sure that you have the Node opt-in to participate in the network.
Node participation can be true or false (online or offline) throughout an Epoch. Participation is in a transient state when the operator requests to opt in or out, and the network has yet to end the undergoing Epoch. Once the Epoch ends, the Node participation transitions to true or false. Therefore, a Node Operator can expect a Node state to be online, offline, opted in or out during an Epoch lifetime.
Before starting the service, make sure to opt-in or opt-out of network participation, through the available subcommand opt in the CLI.
The quickest way to find help is to run the help subcommand as follows:
lgtn opt help
To learn more, read the Lightning-CLI section for command opt.
Launching the node as a systemd service
After completing all the steps and checkups mentioned throughout the guide, you should have the Fleek Network Lightning Service ready to go.
To launch the service, execute the following command:
sudo systemctl start lightning.service
To learn more about how to use Systemctl to manage the Lightning service, read the document here.
Health check
First, complete all the steps and checkups mentioned throught the guide and once the Node process is running perform a health check.
To run a quick health checkup, send a GET request to /health endpoint of the RPC on port 4230.
curl -w "\n" localhost:4230/health
If successful, you should get the response running and staked, as follows:
running and staked
If you'd like to learn more about health check, visit the section health check of our documentation.
Conclusion
The Fleek Network's Ursa CLI is in constant development, there are frequent changes that can introduce features, fixes, and performance improvements, but also breaking changes that in some cases require you to add, including new libraries or packages in your operating system.
In the current phase of development, a proper software release cycle for the updates is still in development, thus we pick changes from the source repository to build the Lightning application.
We have looked into how to pull the changes via Git, and discussed that contributions can introduce new requirements to the host operating system that leads to updates or changes in the documentation–mentioning how hard it is to keep in sync. Explained how to look into the contributions to understand the nature of the change and get hints about new features.
To complete, provided a step-by-step walkthrough the installation and setup process for the Fleek Network Lightning CLI and Systemd service.
Discover more about the project by watching/contributing on GitHub, following us on Twitter, and joining our community Discord for any updates.
